Chapter 9. Using Commands

This chapter describes how to use the Internet Connection Server commands.

cgiparse Command

The cgiparse command handles QUERY_STRING environment variable parsing for CGI scripts. If the QUERY_STRING environment variable is not set, it reads CONTENT_LENGTH characters from its standard input.

This corresponds to the GET and POST methods from HTML forms. QUERY_STRING and CONTENT_LENGTH are environment variables. For a GET request, QUERY_STRING holds the form data. For a POST request, CONTENT_LENGTH is set and the form data is sent on standard input.

Syntax

   cgiparse -Flag [Modifier]

Flags

Flags have one-character equivalents: -k -f -v -r -i -s -p -c -n -q

-keywords

Parse QUERY_STRING as search keywords. Keywords are decoded and written to standard output, one per line.

-form

Parse input as form request. Outputs one or more SET statements that set environment variables beginning with FORM_ followed by a field name. Field values are the contents of the variables.

-value field-name

Parse input as form request. Prints only the value of field-name.

-read

Read CONTENT_LENGTH characters from stdin and write them to stdout.

-init

If QUERY_STRING is not set, read stdin, and output a SET statement that sets QUERY_STRING to its correct value. This can be used when the same script is used with both GET and POST method. A typical use is:

'cgiparse -init > tempfile'
'CALL tempfile'

After this command the QUERY_STRING environment variable will be set regardless of whether the GET or POST method was used. Therefore cgiparse may be called multiple times in the same script. Otherwise with POST it could only be called once because after that the stdin would be already read, and the next cgiparse would hang.

-sep separator

Specify the string used to separate multiple values. Values are:

-value: Default is newline
-form: Default is ", "

-prefix prefix

This flag can only be used with -form. Specify the prefix to use when making environment variable names. Default is "FORM_".

-count

Values are:

-keywords: Outputs the number of keywords
-form: Outputs the number of unique fields (multiple values are counted as one)
-value field-name: Outputs the number of values for field-name (if there is not a field named field-name, output is 0).

-number

For example -2. Values are:

-keywords: Outputs the n'th keyword (for example -2 -keywords outputs the second keyword).
-form: Outputs all the values of the n'th field (for example -2 -form outputs all the values of the second field).
-value field-name: Outputs the n'th of the multiple values of field field-name (for example -2 -value -whatsit outputs the second value of the whatsit field.

-quiet

Suppress all error messages. (Non-zero exit status still indicates error.)

Exit Statuses

0: Success
1: Illegal command line
2: Environment variables not set correctly
3: Failed to get requested information (for example, there is no such field or QUERY_STRING contains keywords when form field values are requested).

cgiutils Command

Use the cgiutils command in no-parse header programs to produce a full HTTP 1.0 response.

Syntax

   cgiutils -Flag [Modifier]

If Modifier contains blanks, enclose it in quotes.

Flags

-version

Print version information.

-nodate

Do not produce the Date: header.

-noel

Do not print a blank line after headers. This is useful if you want to output other MIME headers after the initial header lines.

-status nnn

Give full HTTP response with status code nnn, instead of only a set of HTTP headers. Do not use this flag if you want to produce only the expires field.

-reason explanation

Specify the reason line for the HTTP response. You can only use this flag with the -status nnn flag.

-ct [type/subtype]

Specify MIME content type. For example:

   cgiutils -ct text/html

The following example results in use of the default content type of text/plain

   cgiutils -ct

-ce encoding

Specify content-encoding. For example:

   cgiutils -ce  x-compress

-cl language-code

Specify content-language code. For example:

   cgiutils -dl en_UK

-length nnn

Specify MIME content-length value.

-expires Time-Spec

Specify the time to live in any combination of days, hours, minutes and seconds. For example:

   cgiutils -expires 2 days 12 hours

The cgiutils command adds the time you specify to the current Greenwich Mean Time to determine the expiration date. The expiration date is written on the Expires: header in the HTTP format.

-expires now

Write an Expires: header that matches the Date: header.

-uri URI

Specify the Universal Resource Identifier (URI) for the returned document. URI can be considered to be the same as URL.

-extra xxx:yyy

Specify an extra header that cannot otherwise be specified for cgiutils.

Examples

The following example only calculates the Expires: header:

   cgiutils -expires "1 year 3 months 2 weeks 4 days 12 hours 30 mins"

The following example shows cgiutils with several flags
```
   cgiutils -status 200 -reason "Virtual doc follows" -expires now
```
The above command would produce headers similar to the following:
```
   HTTP/1.0 200 Virtual doc follows
   MIME-Version: 1.0
   Server: IBM-ICS
   Date: Tuesday, 05-Jan-96 03:43:46 GMT
   Expires: Tuesday, 05-Jan-96 03:43:46 GMT
```
There is a blank line after the output to mark the end of the MIME header section. If you want to output some more headers yourself, use the -noel (NO-Empty-Line) flag.
The cgiutils command automatically produces the Server: header because it is available in the CGI environment. The Date: field is also automatically generated unless the -nodate flag is specified.
Note: If you want to supply your own no-parse header (nph) programs specifically to return your own return values, the name of the program must begin with nph-. This prevents the server header from overriding your return value with the standard server return value.
If you do not want the blank line after the header line, use the -noel flag.
```
   cgiutils -noel -expires "2 days" -nodate
```
The above command produces headers similar to the following without a blank line after the headers.
```
   HTTP/1.0 200 Virtual doc follows
   MIME-Version: 1.0
   Server: IBM-ICS
   Expires: Tuesday, 07-Jan-96 03:43:46 GMT
```

htadm Command

Use the htadm command to control your server password files. Your server uses password files to control access to your files. See Chapter 7. "Protecting Your Server" for information about controlling access to your server's resources. With htadm you can add a user name to a password file, delete a user from a password file, change a password for a user, check on a user's password, and create an empty password file.

Note: When you use htadm to add a user, change a password, or check a password, you must enter the password on the command line. Because htadm destroys the password from the command line as soon as possible, it is highly unlikely that you can see a user's password by looking at the process listing on the machine (with the pstat command, for example).

Syntax

   htadm -Flag  Modifier

Flags

-adduser password-file user-name [password [real-name]]

Add a user and password into the password file. If you enter the command with only password-file you are prompted for the other parameters.

password-file

The path and name of the password file you want to add a user name to.

user-name

The user name you want to add.

Use only alphabetic and numeric characters for the user name; do not use special characters.

The command fails if there is already a user of the same name in the password file.

password

The password you want to define for the user name.

Passwords can be up to 32 characters long. Use only alphabetic and numeric characters for the password; do not use special characters.

Note: Some browsers are unable to read and send passwords longer than eight characters. Because of this limitation, if you define a password longer than eight characters, the server recognizes either the complete password or just the first eight characters of the password as valid.

real-name

A comment or name you want to use to identify the user name you are adding. Whatever you enter will be written into the password file.

-deluser password-file [user-name]

Delete a user from the password file. If you enter the command with only password-file you are prompted for the user-name parameter.

password-file: The path and name of the password file you want to delete a user from.
user-name: The user name you want to delete. The command fails if the user name you specify does not exist in the password file.

-passwd password-file [user-name [password]]

Change the password for a user name already defined in the password file. If you enter the command with only password-file you are prompted for the other parameters.

password-file

The path and name of the password file that contains the user name you want to change the password for.

user-name

The user name you want to change the password for. The command fails if the user name you specify does not exist in the password file.

password

The new password you want to define for the user name.

Passwords can be up to 32 characters long. Use only alphabetic and numeric characters for the password; do not use special characters.

-check password-file [user-name [password]]

Check the password for a user name already defined in the password file. If you enter the command with only password-file you are prompted for the other parameters.

password-file: The path and name of the password file that contains the user name you want to check the password for.
user-name: The user name you want to check the password for. The command fails if the user name you specify does not exist in the password file.
password: The password that you want to check. If the password you enter is the one defined for the user name, the command writes Correct to standard output and completes with a 0 return code. If the password you enter is not the one defined for the user name, the command writes Incorrect to standard output.

-create password-file

Create an empty password file.

password-file: The path and name of the password file that you want to create.

Examples

To add a user to a password file

   htadm -adduser d:\tcpip\etc\heroes.pwd clark superman "Clark Kent"

To delete a user from a password file:

   htadm -deluser d:\tcpip\etc\heroes.pwd clark

htimage Command

Use the htimage command to process clickable image maps. The htimage command is located in the CGI Bin scripts directory you specified at installation. The installation default is C:\WWW\CGI-BIN.

The htimage command is a CGI script that executes based upon the regions clicked within a graphics file. The command is used in conjunction with a map file. Map files are text files that maps locations within the graphic to various URLs. See the "Using Images and Multimedia" on our Website for additional information on using htimage and creating map files.

Currently the universal image file accepted by all browsers and servers is the GIF format. GIF is an 8-bit 256 color image file.

You call the htimage command from an anchor tag within an HTML document. (You cannot use htimage from the command line.)

Syntax

Since htimage can only be called from an anchor tag within an HTML document, the syntax is shown as HTML markup.

   <A HREF="/CGI-BIN/htimage/mapfile.txt">
   <IMG SRC="/ICONS/image.gif" ISMAP></A>

<A HREF="/CGI-BIN/htimage/mapfile.txt">

The HREF attribute of the anchor (A) tag specifies the URL of the htimage command followed by the URL of the map file.

This syntax description assumes that the default configuration file is being used. The default configuration file contains an Exec directive that maps requests beginning with /CGI-BIN/ to the directory that contains the htimage command.

The server uses everything following /htimage/ as the URL of the map file. If the server is using the default configuration and the URL contains only a file name, the server would look for the file in the document root directory.

<IMG SRC="/ICONS/image.gif" ISMAP></A>

The SRC attribute of the image (IMG) tag specifies the URL of the file that contains the graphic you want to use as an image map.

The ISMAP attribute indicates that the graphic is an image map.

Examples

Following is a description of the map files that must be used with the htimage command. A map file is a text file. Each line of the file is in the following format:

   region-identifier [region-definition]  URL

region-identifier

A keyword that identifies the type of region being defined. Valid values are:

rectangle
circle
polygon
default.

region-definition

A set of numbers that defines a particular region of the graphic. The format of the region definition is different for each type of region.

Coordinates within parentheses identify a point relative to the top left corner of the image. The first number is the number of pixels to the right of the top left corner. The second number is the number of pixels down from the top left corner. There are several shareware programs available that can help you easily identify the coordinates of particular points within a graphic file.

default   URL
rectangle (x1,y1) (x2,xy) URL
circle    (x,y)   r       URL
polygon   (x1,y1) (x2,y2) (x3,y3) URL

The default keyword does not define a region. The keyword is followed by a URL to link to when the client clicks on a portion of the image map that is not covered by any of the other region definitions.
For rectangle, the first point is the upper left corner of the rectangle. The second point is the lower right corner. In other words, define any two diagonally opposite corners having coordinates (x1,y1) and (x2,y2).
For circle, the point is the center of the circle. The single number following the point is the radius of the circle as measured in pixels.
For polygon, up to 100 points can be defined. The shape is formed by connecting the points in the order they are given. The last point is connected to the first.

For example, you might use the following HTML in a document:

   <A HREF="/cgi-bin/htimage/mapit.txt">
   <IMG SRC="/icons/mapimage.gif" ISMAP></A>

The above example calls the htimage command with a map file named mapit.txt. The mapit.txt file would define regions of the mapimage.gif graphic file. Because no path is specified for mapit.txt, the server would look for it on the document root directory. Following is an example of what mapit.txt might look like.

   default                                   /cgi-bin/go_home
   rectangle (50, 100) (200,200)             /cgi-bin/go_to_it
   circle    (100,300) 50                    /pub/example.html
   polygon   (450,350) (450,500) (150, 500)  /pub/triangle.html

One example of a shareware program for determining the x,y coordinates is mapedit. You can obtain mapedit from the following URL:

http://sunsite.unc.edu/~boutell/mapedit/mapedit.html

whttpg Command

Use the whttpg command to start the Internet Connection Server.

You can use the Directory argument, to indicate the directory to be exported. If not present, a rule file can be used to export combinations of directories. The default setting is to export the /Public directory tree.

You can set all these flags (except -r) using the directives in the server configuration file. You can set the directory-browsing flags with the DirAccess configuration directive. It is common practice to create a file named README containing instructions or notices to be read by anyone new to the directory. whttpg will by default imbed any README file in the hypertext version of a directory. The README file instructions can also be set with the DirReadme configuration directive.

Syntax

   whttpg [-Flag [-Flag [-Flag..]]]

-r configuration-file: Use this file as the configuration file. You must use this flag if you want to start the server with a configuration file other than the default configuration file.
-p port-number: Listen to this port number. The default port number is 80.
-l log-file: Use this file to log requests.
-restart: Restart an already running Internet Connection Server program
-gc_only: Do only garbage collection and then exit. This flag is used only for caching proxy servers.
-version: Print the version number of httpd and libwww (the WWW Common Library).
-dy: Enable directory browsing. By default, directories can be returned as hypertext documents. This is the default setting. You can combine -dy with the -db and -dt options (for example, -dyb, -dty).
-dn: Disable directory browsing. The server responds with an error message to requests for a directory listing.
-ds: Selective directory browsing. Directory browsing allowed only for directories containing a file named .www_browsable.
-dt: For any browsable directory that contains a README file, include the text of the README file at the top of the document before the listing. This is the default setting. You can combine -dt with the -db and -dy options (for example, -dtb, -dty).
-db: Same as the -dt flag but puts the README at the bottom, after the listing. You can combine -db with the -dy and -dt options (for example, -dyb, -dtb).
-dr: Disables the README inclusion feature.

Examples

To specify a standalone server running on port 80, using the D:\TCPIP\httpd.config configuration file instead of the default configuration file:
```
   whttpg -r D:\TCPIP\httpd.config  -p 80
```
If the Port directive is given in the configuration file, the -p flag is not required. The -p flag can be used to override the value set in the configuration file.

[ Top of Page | Previous Page | Next Page | Table of Contents ]